fix(hooks): a linked worktree is one whose git-dir differs from its git-common-dir - #7749

ACCEPT — lands #7259 as ruled, one flight with objectstack PR #15924 (#11809). Governed (.claude/**), so this PR stays draft at the governed terminal: both approvers requested; needs-user-decision goes on the PR with the final 「维护者速读」 posted beneath this verdict. The two repos must merge together — the executable lines are identical and the guards' whole value is that they agree.

What the seat verified, at head 2248bbad82, in its own compare worktree

• Four files, +89/−40: both guards replace the */worktrees/* substring case with the structural test (--absolute-git-dir ≠ --git-common-dir, the relative common-dir resolved against the queried directory, one canon_dir helper); a failed rev-parse keeps today's behaviour.
• Direct reproduction by the seat on a fresh fixture (TMP/worktrees/oddrepo, a PRIMARY checkout): the new hook answers ODD/pkg/x.ts with rc 2 (block), where the substring test allowed it.
• All four .claude/hooks/*.selftest.sh green on the head: 126 · 116 · 48 · 36 passed, 0 failed; the Bash matrix gained the ODD fixture (121 → 126); the Edit/Write matrix's four ODD cases now all expect block; KNOWN HOLE residue 0; the PORTED header's two stale sentences corrected.
• Cross-repo parity, seat's own read: comment-stripped guard-main-checkout.sh is line-identical between this head and objectstack PR #15924's head.
• This repo has no skip-changeset label and none was invented; check-changeset-presence reads no changeset owed (no published source changed). Body line 1 Fixes #7259. CI, seat's read 15:1xZ: 30 check runs, 27 success, 3 skipped, none failing, none pending (Hook Self-Tests and Governed Surface Queue Guard among the green).

Reconciliation: the 13:59Z Claim: comment's branch spelling and its "first pair only" scope for this repo were the seat's text, superseded by the dispatch brief the dev correctly followed; the seat edits its own claim comment to what landed.

Implemented-by: os-dev executor, flight objectui #7259 + objectstack #11809, branches claude/issue-7259-structural-linked-worktree-test / claude/issue-11809-structural-linked-worktree-test
Reviewed-by: pm-dispatch skills seat, https://claude.ai/code/session_019RfFHiRCSs3JXLK4cwcfox

Generated by Claude Code

维护者速读

改了什么:两个「禁止改共享主检出」的守卫钩子(Edit/Write 那个和 Bash 那个)判断「当前是不是 linked worktree」的方法换掉:原来看路径里有没有 worktrees 这几个字,现在问 git 的结构事实(git-dir 与 git-common-dir 是否不同,不同才是 linked worktree)。四个文件:两个钩子 + 两个自测矩阵;objectstack PR #15924 同步落一份,可执行行逐行相同。

为什么改:守卫的唯一职责是拦住往共享主检出里写。原判据在最常见的布局下失效:仓库放在名为 worktrees 的目录下(如 ~/worktrees/objectui),改任何子目录里的已有文件都被放行,且无任何报错;顶层文件反而被拦,让人误以为守卫在工作。席位在干净夹具上直接复现:新钩子拦截(rc 2),旧判据放行。

风险与代价(含回滚):方向是收紧(以前放行的现在拦),理论代价是误拦;本仓四个矩阵 326 用例全绿(两仓合计 379),含子模块、真 linked worktree、非仓库目录三类正向场景。关键坑已实测并写进注释:--git-common-dir 打印相对路径,不先解析会让守卫在所有深度失效(实测 47 用例翻车),所以「换 --absolute-git-dir 即可」的说法是错的,未采纳。无新依赖。本仓不欠 changeset(check-changeset-presence 判定未动任何发版包源码,不是走豁免)。回滚 = revert 一个 commit。两仓必须一起合。

席位意见:建议批准,两仓同批。四轴:业务——守卫在最常见布局下失效是实测的;长远——用 git 的结构判据替代路径猜测;防 AI 错——这正是防 agent 误写共享树的那道门;创业阶段——四文件、无新依赖、不扩面。

你要做的:两仓一起批准并人工合并(本 PR 与 objectstack #15924)。一字:是/否。

Generated by Claude Code

Status for the approvers: the objectstack half of this flight, PR #15924, MERGED at 16:03:37Z (924f0fed1). Until this PR lands, the two repos' worktree-first guards read a linked worktree by different tests (structural there, substring here), which is the divergence the pair was ruled to avoid. Nothing else changed on this head (2248bbad82; 30 checks green); the seat's ACCEPT and 速读 above stand.

Generated by Claude Code

Ruling recorded — approved; the maintainer has queued it (director seat, decision batch #72, 2026-09-07)

Maintainer reply, verbatim: 「7749 已加入队列，其他同意」.

The maintainer approved this PR and added it to the merge queue themselves (timeline: added_to_merge_queue by os-zhuang at 2026-09-07T06:09:06Z). .claude/hooks/ is a governed surface, so the merge is the maintainer's own; the PM seats do not touch it.

Recorded for the ledger:

• A previous queue entry (2026-09-07T03:25:35Z) was removed by the merge-queue bot at 03:34:17Z. If the queue rejects it again, that is the maintainer's to re-run or to re-price — this ruling stands either way.
• The sibling objectstack PR #15924 carries the same defect and the same fix; it is on the same governed path and likewise awaits the maintainer's own merge.

needs-user-decision → pm:queue.

Generated by Claude Code

Why the merge queue evicted this PR twice — a real red, and it needs a patch round before the maintainer re-queues (director seat, 2026-09-07 07:4x UTC)

Read from the merge-group run of 06:09Z (gh-readonly-queue/main/pr-7749-…): the PR-side checks are all green on 2248bbad82, but two queue jobs fail on the same gate —

• Lint → step Verify the ported objectstack tooling still matches its pin (node scripts/check-upstream-port-parity.mjs), and
• Test (shard 1/4) → scripts/__tests__/upstream-port-parity-wiring.test.ts "and the tree itself is at parity right now", which shells out to the same gate.

Verdict, verbatim:

✗ .claude/hooks/guard-main-checkout.selftest.sh: DRIFTED from the pinned upstream copy.
    divergence `known-hole-notebook-section-removed`: expected its ported text exactly once, found 0
    divergence `hole-crossref-repointed`: … found 0
    divergence `hole-heading-repointed`: … found 0
    divergence `notebook-verdict-by-its-own-path`: … found 0
    divergence `ported-from-provenance-header`: … found 0
    Upstream is objectstack-ai/objectstack; the pin currently names bf10debd587f6ba891be9eadc2b76c91e15bd82b.
✗ check-upstream-port-parity: 1 of 3 ported file(s) drifted. ⛔ Do not edit the pinned digest by hand to clear this

Mechanism. guard-main-checkout.selftest.sh is a ported copy of objectstack's file, pinned to objectstack bf10debd5 with five declared divergence regions — several of them describing the very KNOWN HOLE block this PR deletes. The queue build merges main (where that gate now runs) with this branch, the declared regions no longer exist, and the gate reads that as drift. It is not flakiness and a re-queue will fail the same way.

Patch round (this PR's lane, not the maintainer): re-sync the pin to the objectstack commit that landed the sibling fix (#15924 merged as 924f0fed1 on 2026-09-05) using the gate's own procedure — --resync <upstream file> --ref <sha> — and re-declare the divergences that still exist against that upstream; ⛔ never hand-edit the digest. Then re-run the parity gate and the wiring test locally, push, and ask the maintainer to re-queue. .claude/hooks/ stays governed: draft-for-human-merge posture unchanged; the maintainer's approval and ruling (batch #72) stand.

Generated by Claude Code

Patch round: the merge-queue gate is green

Pushed head: 92af28038f358d45c30603d5daa2331b9e565669 (92af2803), no force-push. Two commits added on top of 2248bbad: a merge of origin/main (so the gate I ran is the one the queue runs), then the fix.

Red first, on the merged head, before anything changed

node scripts/check-upstream-port-parity.mjs — exit 1, reproducing the queue verdict exactly:

✗ .claude/hooks/guard-main-checkout.selftest.sh: DRIFTED from the pinned upstream copy.
    divergence `known-hole-notebook-section-removed`: expected its ported text exactly once, found 0
    divergence `hole-crossref-repointed`:            expected its ported text exactly once, found 0
    divergence `hole-heading-repointed`:             expected its ported text exactly once, found 0
    divergence `notebook-verdict-by-its-own-path`:   expected its ported text exactly once, found 0
    divergence `ported-from-provenance-header`:      expected its ported text exactly once, found 0
✗ check-upstream-port-parity: 1 of 3 ported file(s) drifted.

What the re-sync changed

Pin ref bf10debd587f6ba891be9eadc2b76c91e15bd82b → 70e77ec3b566b92d7c6551637d6bc746fb840bb6, moved only by the gate's own procedure. No digest was hand-edited:

node scripts/check-upstream-port-parity.mjs --resync /tmp/upstream-selftest.sh \
  --ref 70e77ec3b566b92d7c6551637d6bc746fb840bb6 \
  --path .claude/hooks/guard-main-checkout.selftest.sh --rewrite-governed-file

exit 0. --rewrite-governed-file is the flag it demands for a .claude/** path, and it said so by name before writing.

Declared divergences for this file: 14 → 2. Upstream has since absorbed twelve of them, which is the direction the pin's own header says the set is meant to move.

Dissolved, because upstream now carries the same text: routed-key-header-sentence, nbpay-payload-helper, tool-name-selects-path-key-section, routed-tool-missing-key-is-drift-section, nopath-probe-uses-an-unrouted-tool, nojq-notebook-and-tool-name-decoy-rows, wiring-section-pins-the-matcher-pairing, matcher-to-table-pairing-block, notebook-verdict-by-its-own-path, hole-heading-repointed, hole-crossref-repointed, known-hole-notebook-section-removed, mutation-recipe-classes. --resync did not refuse on any anchor.

diff between the re-synced file and upstream at that ref shows those two regions and nothing else, so the header's claim that the port is VERBATIM is now literally true.

Which hunks came from which upstream PR

objectstack#15924 (924f0fed1, the sibling of this PR) — already present on this branch before my round. The structural section and its four block rows were byte-identical to upstream's apart from the card number, so the re-sync carried them straight through. Nothing was ported for #15924; the branch had it right.

objectstack#15987 (c2520416c, "the guards' escape hatch names where it actually works") — this branch was behind, and these lines are new here:

1. .claude/hooks/guard-main-checkout.selftest.sh — the stderr_of / says / lacks helpers, and the section == the hatch names WHERE it works: this hook's own environment, never a prefix == with its four assertions. Arrived via the re-sync as ordinary upstream text.
2. .claude/hooks/guard-main-checkout.sh — the escape-hatch wording at both of its message sites (the ordinary refusal and the schema-drift refusal). Deliberate non-task exception: re-run with OS_ALLOW_MAIN_EDITS=1. becomes the four-line sentence naming the environment the hook actually reads.

Point 2 is not optional decoration: the ported rows assert the hook's refusal text (lacks 're-run with', says 'hook itself runs in'), so without it the re-synced matrix would fail. On-disk landing was proven by an occurrence count before/after — the dead remedy 2 → 0, the new wording 0 → 2 — not by the editor's exit code.

That also repairs the provenance header's own measurement. The two repos' guard-main-checkout.sh now differ by 10 diff lines, all inside comment blocks, no executable line differing — re-measured with diff, and exactly what the header sentence claims. The residual is the cross-ref line plus upstream's ⭐ recipe-alignment comment block, which carries objectstack card numbers and is deliberately not ported.

Gate verdicts — exit codes captured before any pipe

All at 92af2803, working tree clean.

Hook self-tests, all exit 0:

The +4 is exactly the #15987 section's four rows. The other three matrices are unmoved.

Changeset — verified with the script, not assumed:

Compared the working tree with fc32921aa (merge-base with origin/main): 5 file(s) changed,
0 of them published source of a package the release covers, 0 of them a manifest whose
published contract moved, 0 under a package changesets ignores, 0 changeset(s) added.
✅  No source or published contract of a released package changed in this range, so no changeset is owed.

Whole-repo lint is a real full run, not a narrowing. For the record all three changed files are outside eslint's population — --format json reports File ignored because no matching configuration was supplied. for each — and no type-aware linting is configured, so this diff cannot move any untouched file's verdict.

Ablation

From the committed state, reverting the pin bump alone (git checkout 92af2803^ -- scripts/upstream-port-pin.json, leaving the re-synced self-test in place):

• mutation proven on disk before the reading was trusted: ref back to bf10debd58…, divergence count back to 14, on-disk blob b57ffd03… ≠ HEAD blob c2b7b1e1…
• the gate: exit 1, 1 of 3 ported file(s) drifted, naming the same five divergences in the same order as the queue log
• restored with git checkout HEAD -- …; disk blob c2b7b1e1… equals the HEAD blob c2b7b1e1… and git diff HEAD is empty; gate back to exit 0

So the pin bump is load-bearing, and the restore is proven by hash rather than by a clean exit code.

Two things for the maintainer, neither fixed here

1. The pin's ref is global, its digests are per-file — so any single-file re-sync makes the other entries' printed provenance false. resync() sets pin.upstream.ref unconditionally while updating only the re-synced entry's digest. The gate now prints, for the two files I did not touch:

✓ scripts/pm/check-half-states.mjs: byte-identical to …@70e77ec3b:… modulo 11 declared divergence(s).
✓ scripts/invoked-as.mjs:           byte-identical to …@70e77ec3b:… modulo 9 declared divergence(s).

Both statements are false as to the ref. Measured:

They stay green — the digest comparison is the assertion and their bytes are untouched — but the ref beside them now names a tree their digests were not taken from. I did not resync them, and I could not have made the ref fully honest in this round either way. Probing both with the gate's own rewrite(…, 'forward'):

• scripts/invoked-as.mjs — all 9 divergences still apply; a mechanical re-sync (138 diff lines).
• scripts/pm/check-half-states.mjs — 5 of 11 divergences no longer apply (summary-unread-branch, closed-window-resolver, closed-window-fetch-gate, summary-disabled-beats-floor, closed-window-self-test), and upstream has moved ~8,600 diff lines. That needs those five re-decided by hand: its own card, not a rider on a hooks PR.

Repairing the printed provenance properly means a per-file ref in the pin, which is an edit to scripts/check-upstream-port-parity.mjs — out of bounds for this round by instruction, and reported rather than attempted.

2. The Bash sibling still prints the remedy #15987 removed. guard-main-checkout-bash.sh ends both refusals with Deliberate non-task exception: re-run with OS_ALLOW_MAIN_EDITS=1. — the instruction that cannot work where it is printed. It is not in the pin and its own matrix asserts nothing about the message, so nothing catches it, and the two guards now disagree about their shared hatch. Left alone deliberately: outside this round's scope, and it needs the says/lacks rows ported alongside it to be worth anything.

PR state — untouched, and one thing I did not do

• The approval survived the push. Two APPROVED reviews from os-zhuang (a GOVERNED_APPROVERS member) are on the PR, left on 2248bbad. Per the queue guard's own message the review counts "on whichever commit it was left (maintainer ruling 2026-09-04)", so the push did not cost it.
• The PR is currently draft: false. I did not flip it, and I have not flipped it back — that state was set by another actor and reverting it is not mine to do. Flagging it because the body says the PR is parked as a draft, and because .claude/** is governed surface. Nothing was enqueued, no auto-merge armed, no review submitted.
• pm:queue label untouched; base is main; 5 files changed across 3 commits.

Re-queue at your convenience — the gate that failed twice is green at 92af2803.

Generated by Claude Code

Patch round landed on the branch — head 92af28038; for the maintainer: re-queue once CI is green (director seat, 2026-09-07 08:4x UTC)

The dev seat reproduced the queue's red first (same five zero-occurrence divergences), then re-synced the ported self-test with the gate's own --resync … --ref 70e77ec3b --rewrite-governed-file — no digest hand-edited, the gate script untouched. Upstream had absorbed 12 of the 14 declared divergences (14 → 2). objectstack#15924's structural section was already identical here; objectstack#15987's escape-hatch wording and its four self-test rows were new and are now ported into both the hook and its self-test, so the two repos' hooks differ by comment lines only.

Readings at 92af28038 (exit codes captured before any pipe): parity gate exit 0 (3/3 files match modulo declared divergences); gate self-test 49/49; wiring test 10/10 from the repo root; hook self-tests 120 / 126 / 48 / 36 passed, 0 failed (+4 = the #15987 rows); check:control-bytes 0; changeset presence: none owed (measured); root pnpm lint 47/47, 0 errors. Ablation: reverting the pin bump alone reproduces the queue's five-divergence red; restore proven by blob hash.

Two findings the seat could not fold in are filed: objectui#8271 (the Bash guard still names the dead OS_ALLOW_MAIN_EDITS=1 remedy) and objectui#8272 (the pin's one global ref vs per-file digests).

Posture: .claude/hooks/** governed; nothing flipped, queued, armed or approved by a seat. The maintainer's two approvals are on 2248bbad8; CI on the new head is running (18 green, 9 in progress at the time of writing). When it is green, one "merge when ready" click puts it back in the queue.

Generated by Claude Code

Correction to the comment above: the two follow-up findings are #8287 (Bash guard's dead OS_ALLOW_MAIN_EDITS=1 remedy) and #8288 (pin's global ref vs per-file digests) — not #8271 / #8272, which I wrote before the cards were created. Director seat error, recorded rather than edited away.

Generated by Claude Code